Formats

     Output record formats for use with the  write  operator  may
     declared as follows:

         format NAME =
         FORMLIST
         .

     If name is omitted, format "STDOUT"  is  defined.   FORMLIST
     consists of a sequence of lines, each of which may be of one
     of three types:

     1.  A comment.

     2.  A "picture" line giving the format for one output line.

     3.  An argument line supplying values to plug into a picture
         line.

     Picture lines are printed exactly as they look,  except  for
     certain  fields  that substitute values into the line.  Each
     picture field starts with either @ or ^.  The @  field  (not
     to  be confused with the array marker @) is the normal case;
     ^ fields are used to do rudimentary  multi-line  text  block
     filling.  The length of the field is supplied by padding out
     the field with multiple <, >, or |  characters  to  specify,
     respectively,  left  justification,  right justification, or
     centering.  As an alternate form of right justification, you
     may  also use # characters (with an optional .) to specify a
     numeric field.  (Use of ^ instead of @ causes the  field  to
     be blanked if undefined.)  If any of the values supplied for
     these fields contains a newline, only the  text  up  to  the
     newline  is  printed.   The special field @* can be used for
     printing multi-line values.  It should appear by itself on a
     line.

     The values are specified on the following line, in the  same
     order as the picture fields.  The values should be separated
     by commas.

     Picture fields that begin with ^ rather than @  are  treated
     specially.   The  value  supplied  must be a scalar variable
     name which contains a text string.  Perl puts as  much  text
     as  it  can  into the field, and then chops off the front of
     the string so that the next time the variable is referenced,
     more  of  the text can be printed.  Normally you would use a
     sequence of fields in a vertical stack to print out a  block
     of text.  If you like, you can end the final field with ...,
     which will appear in the output if the text was too long  to
     appear in its entirety.  You can change which characters are
     legal to break on by changing the variable $: to a  list  of
     the desired characters.

     Since use of ^ fields can produce variable length records if
     the  text  to  be formatted is short, you can suppress blank
     lines by putting the tilde (~)  character  anywhere  in  the
     line.  (Normally you should put it in the front if possible,
     for visibility.)  The tilde will be translated  to  a  space
     upon  output.   If  you put a second tilde contiguous to the
     first, the line will be repeated until all the fields on the
     line  are  exhausted.  (If you use a field of the @ variety,
     the expression you supply had better not give the same value
     every time forever!)

     Examples:

     # a report on the /etc/passwd file
     format STDOUT_TOP =
                             Passwd File
     Name                Login    Office   Uid   Gid Home
     ------------------------------------------------------------------
     .
     format STDOUT =
     @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
     $name,              $login,  $office,$uid,$gid, $home
     .

     # a report from a bug report form
     format STDOUT_TOP =
                             Bug Reports
     @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
     $system,                      $%,         $date
     ------------------------------------------------------------------
     .
     format STDOUT =
     Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
              $subject
     Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
            $index,                       $description
     Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
               $priority,        $date,   $description
     From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
           $from,                         $description
     Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                  $programmer,            $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
                                          $description
     ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
                                          $description
     .

     It is possible to intermix prints with writes  on  the  same
     output  channel, but you'll have to handle $- (lines left on
     the page) yourself.

     If you are printing lots of fields that are  usually  blank,
     you   should  consider  using  the  reset  operator  between
     records.  Not only is it more efficient, but it can  prevent
     the bug of adding another field and forgetting to zero it.